home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / utility / ffe101.zip / ANIM.SWG / 0012_GL (GRASP).pas < prev   
Pascal/Delphi Source File  |  1997-02-15  |  29KB  |  807 lines
  1. The formats of GRASP animation files.
  2. By George Phillips <phillips@cs.ubc.ca>
  3. Distribute this freely, but give credit where credit is due, eh?
  4. Version: Jan. 19,1991
  5.  
  6. GRASP is an animation system particular to the IBM PC world.  It consists
  7. of a program to create animations and a run-time environment for
  8. displaying them.  The most common form these animations take is ".GL"
  9. archives which may be displayed on an IBM-PC with a program called
  10. GRASPRT.EXE.  This document describes what I have been able to
  11. decipher about the format of ".GL" archives and the files contained
  12. within.  It should be useful to those attempting to write ".GL"
  13. animation players on other platforms.
  14.  
  15. A ".GL" file is simply an archive file which contains images, fonts
  16. and a command file which tells GRASPRT what to do.  These various
  17. files have standard extensions to denote their contents:
  18.  
  19. .txt - A command file; usually there is only one of these per archive.
  20. .pic - An image.
  21. .clp - An image but without a colour map.
  22. .set or .fnt - A font containing character glyphs.
  23.  
  24. It should be noted that the GL archive is of no particular importance;
  25. all the archived files could exist as ordinary files and the animation
  26. should still work.  Any GL player should be able to operate both from
  27. an archive or from ordinary files.
  28.  
  29.  
  30. File Formats
  31.  
  32. Most of the data in GL files can be adequately described as a stream
  33. of bytes which is practically universally understood.  Some fields
  34. contain 2-byte and 4-byte integers.  I'll refer to these as "words"
  35. and "long words" and they are all stored in little-endian format.
  36. So if we have 4 consecutive bytes, b1, b2, b3 and b4, the word
  37. at b1 is (b1 + b2 * 256) and the long word at b1 is
  38. (b1 + b2 * 256 + b3 * 256 * 256 + b4 * 256 * 256 * 256).
  39.  
  40. Since this information was gathered by example, the purpose of some
  41. header fields and commands may not be known.  I've marked unknown
  42. fields with question marks and have tried to put question marks and
  43. other warnings about descriptions which are guesses.
  44.  
  45.  
  46. GL Archives (.gl)
  47.  
  48. A GL archive begins with a directory listing the files in the archive
  49. which is followed by the data for each file.
  50.  
  51. +-- Directory Header
  52. | dir length    (word)        number of bytes in the directory header
  53. | +-- File Entry (17 bytes per, (dir length) / 17 of them)
  54. | | offset    (long word)    Position of file data as an offset from
  55. | |                the beginning of the archive
  56. | | name    (13 bytes)    File name, null padded.
  57. | +--
  58. +--- File data area
  59. | +-- File Data
  60. | | length    (long word)    Size of the file
  61. | | data    (bytes)        the file's data (surprise!)
  62. | +--
  63. +---
  64.  
  65. Font Files (.fnt or .set)
  66.  
  67. These are very simple; first a short header describing the size of the
  68. characters in the font and what byte values correspond to each glyph
  69. followed by the glyph data.
  70.  
  71. +-- Font Header
  72. | length    (word)        length of the entire font file
  73. | size        (byte)        number of glyphs in the font file
  74. | first        (byte)        byte value represented by the first glyph
  75. | width        (byte)        width of each glyph in pixels
  76. | height    (byte)        height of each glyph in pixels
  77. | glyphsize    (byte)        number of bytes to encode each glyph
  78. +-- Glyph Data
  79. | glyph first
  80. | glyph first + 1
  81. | ...
  82. | glyph first + size - 2
  83. | glyph first + size - 1
  84. +--
  85.  
  86. Each glyph is stored almost exactly as you would expect a raw PBM file to
  87. contain it except that a '0' bit means black and a '1' bit means white.
  88. In other words, row major order, each line padded to end on a byte
  89. boundary, most significant bit is leftmost.
  90.  
  91.  
  92. Image Formats (.pic and .clp)
  93.  
  94. These consist of a header containing the usual image information followed
  95. by blocked, run-length encoded image data.
  96.  
  97. +-- Image Header (17 or 19 bytes)
  98. | magic?    (byte)        magic number?  Always is 0x34 or 0x12
  99. | width        (word)        width of image in pixels
  100. | height    (word)        heigh of image in pixels
  101. | ????        (4 bytes)    unknown
  102. | bpp        (byte)        bits per pixel (only seen 1 or 8)
  103. | type        (byte)        image type, either 'L' or 'C'
  104. | flags        (byte)        if (flags & 4) then image has colourmap
  105. | ?        (byte)        unknown
  106. | extend    (byte)        extended header byte (if != 0, header
  107. |                has 2 more bytes) 1/2?
  108. | ?        (byte)        unknown
  109. | ??        (2 bytes)    header extension if extend != 0
  110. +-- Colour Map ((1 << bpp) * 3 bytes, only if flags & 4 == 4)
  111. | +-- Colour Map entries (as many as indicated by bpp)
  112. | | R        (byte)        red intensity, 0 - 63   \
  113. | | G        (byte)        green intensity, 0 - 63  + entry 0
  114. | | B        (byte)        blue intensity, 0 - 63  /
  115. | +--
  116. | ...
  117. +-- Image Data
  118. | blocks    (word)        number of blocks of data
  119. | +-- Data Block (blocks of them)
  120. | | length    (word)        length of data block, including header
  121. | | bufsize    (word)        buffer size needed to hold all the
  122. | |                uncompressed data in this block
  123. | | esc        (byte)        the escape code in this block
  124. | | data    (length - 5 byte)    run-length encoded data
  125. | +--
  126. +--
  127.  
  128. The run-length encoding is byte oriented and follows these rules:
  129.  
  130. - characters other than "esc" (see data block header) are literal
  131. - esc n c means repeat c n times (1 <= n <= 255)
  132. - esc 0 len(word) c means repeat c len times
  133.  
  134. If bpp=1, then the resulting data stream is interpreted as it is
  135. with font glyphs (i.e., msb is left, pad to bytes, row first, etc).
  136. If bpp=8, then each byte in the data stream is an index into the
  137. colour map.  If no colour map is available, the map to use can
  138. only be discovered by running through the command file.
  139.  
  140. I've only seen images with bpp=1 and bpp=8 and they it always works
  141. out that either bpp=1 and type=C or bpp=8 and type=L.  The type=C
  142. corresponds to CGA graphics which are mostly monochrome and 640 x 200
  143. (so the aspect ratio is funny).  Type=L is colour graphics, prob. VGA
  144. and usually 320 x 200.  Notice that the colour maps have only 6
  145. bits, the same as VGA's digital to analog converters.  ".pic" files
  146. always have colour maps, ".clp" files never do.  It seems that
  147. you can be lazy with your run-length decoding code; I've never seen
  148. a full sequence appear across a data-block boundary (encoders should
  149. probably not let that happen).  The amount of uncompressed data
  150. in a block never seems to exceed 8192 bytes.
  151.  
  152. Much of the header information is mysterious.  Note that the header
  153. extension field is a guess and that there are other consistent
  154. possibilities (e.g., the extension field is a length byte or even
  155. part of a length word).  Only type=C images seem to have the
  156. extension.  Maybe the extra information is supposed to be used
  157. in video mode operating system calls on the PC?
  158.  
  159. What made this part easier was the existence of a PC-based program which
  160. converts ".pic" files into GIF files.  Its called "cvt2gif" and can
  161. be found on wuarchive.wustl.edu:/mirrors/msdos/gif/cvt2gif.zip.  Those
  162. wishing to enhance the format descriptions would do well to get a
  163. copy.  I did notice that bpp=1 images are not necessarily black and white
  164. but could be black and some other colour as selected from the CGA
  165. pallette.  I doubt the distinction will make much difference to the
  166. animation, but if you really want to do it right...
  167.  
  168.  
  169. Command File (.txt)
  170.  
  171. The command file looks like a typical script file with the lines delimited
  172. by carriage returns, line feeds or both.  Any text following ';' on a line
  173. is a comment.  Text followed by a colon is used to indicate a label
  174. (much like most assemblers).  Commands consist of a keyword followed by a
  175. list of comma separated arguments.  The input is case-insensitive except
  176. for arguments containing text to display (which are in double quotes).
  177.  
  178. The basis of the command language seems to be what I call picture and
  179. clip registers, of which there are 16 of each.  A few commands will
  180. load a picture (or clip) from a file into a register.  Other commands
  181. then reference the register numbers to display the pictures or get
  182. colour maps from them.  It seems that the colour map from a picture
  183. (.pic) is installed into the hardware and this is where the
  184. colour maps for the clips (.clp) come from.  I assume that I am missing
  185. a lot of commands, but most notably I believe there should be
  186. more primitive drawing commands.
  187.  
  188. Many of the commands seem to have a delay argument associated with
  189. them.  This seems reasonable as control over time in an animation
  190. is important.  I may have been over-zealous in looking for delays.
  191. The actual time units of the delays is unknown.  They are typically
  192. numbers < 100, so milliseconds are a likely candidate.  Hundredths
  193. of a second are possible as well.
  194.  
  195. Here is a list of commands.  Optional arguments are enclosed in [].
  196. Ranges are possible in arguments (I've only seem them in fly) and
  197. take the form "n,-,m", (e.g., fly 0,0,10,10,1,1,1,-,16).
  198.  
  199. * box x1,y1,x2,y2,colour?
  200. Draw a box with corners (x1, y1) and (x2, y2) in the colour given by
  201. the colourmap entry number.
  202.  
  203. * cfade x,y,delay,img,[,?,?]
  204. Display a clip image img at (x, y) and wait for delay time units before
  205. proceeding.
  206.  
  207. * cfree n
  208. Free up any memory associated with clip register n.
  209.  
  210. * clearscr
  211. Clear the display (to the currently selected colour or black?).
  212.  
  213. * cload name,num[,?]
  214. Load a clip image "name" into clip register num.  If name does not
  215. have a .clp extension, it will be automatically appended.
  216.  
  217. * color n
  218. Set the current colour to n.  This at least seems to affect the
  219. text displaying commands.
  220.  
  221. * exit
  222. Terminate the command file.
  223.  
  224. * fload name
  225. Load the named font which becomes the font to be used when displaying
  226. text.  ".fnt" is appended to name if necessary.
  227.  
  228. * float x1,y1,x2,y2,step?,delay?,num
  229. Move the clip image (num) by displaying it at (x1,y1) and erasing it
  230. and displaying it every step pixels until (x2,y2).  Delay delay time
  231. units in between steps.  Or maybe something completely different,
  232. but the x1,y1,x2,y2 and num arguments are probably coordinates and
  233. a clip number.
  234.  
  235. * fly x1,y1,x2,y2,step?,delay?,clip list
  236. Successively display the clip images from (x1,y1) to (x2,y2) with delay
  237. time units in-between.  The clip list is just a bunch of clip numbers
  238. separated by commas (i.e., fly is varags).  A range is likely to
  239. appear in the clip list.  Often (x1,y1) == (x2,y2).
  240.  
  241. * fstyle ?[,?]
  242. Presumably set up some parameters on how a font is displayed.
  243.  
  244. * goto label
  245. Force flow of control to the given label.
  246.  
  247. * loop
  248. Denotes the end of a mark loop.  Continues the loop at the most recent
  249. mark if the loop hasn't finished.  
  250.  
  251. * mark n
  252. This pairs with the loop command and begins a for loop from 1 to n.
  253. One assumes that the interaction of mark, loop and goto is the same
  254. as for, next and goto in BASIC.  That is, loops are dynamically
  255. scoped and you can jump in and out of them.  Mark simply pushes
  256. a loop start onto the stack and loop examines whatever is on
  257. the top of the loop stack.
  258.  
  259. * mode ?
  260. Modify the current video mode in some way.  I haven't seen this often.
  261.  
  262. * note freq,delay?,duration
  263.  
  264. Play a musical note of the given frequency and duration and delay for
  265. delay time units afterward.
  266.  
  267. * pallette n
  268. Make the colour map from picture register n be the one to use.  This probably
  269. installs it into the hardware so that when a clip is loaded there is
  270. no colour map to change.
  271.  
  272. * pfade effect,pict[,delay?[,?,?]]
  273. Display the picture numbered pict on the screen.  The effect number
  274. indicates what sort of special effect is used to display it.  What
  275. the numbers mean I have no idea, but I know some of the effects.
  276. Each pixel loaded randomly, every even line then every odd line
  277. and so on.  The delay parameter seems to make sense, but not always.
  278. The extra parameters could be those needed for some effects.  Often
  279. they are large numbers.
  280.  
  281. * pfree n
  282. Free up any memory associated with picture register n.
  283.  
  284. * pload name,n
  285. Load picture "name" into picture register n.  ".pic" is appended to
  286. name if necessary.
  287.  
  288. * putup x,y,n
  289. Display clip register n at (x,y).
  290.  
  291. * set retrace [on|off]
  292. Set is probably a general internal control variable changing command.
  293. What retrace is I have no idea, but it was set off then on around
  294. a fly statement.
  295.  
  296. * spread ?,?
  297. Who knows, but the numbers used are probably picture register numbers.
  298. Maybe some kind of colourmap changing?
  299.  
  300. * text x,y,"text",[delay?]
  301. Display the given text (enclosed in double quotes) at (x,y).  The
  302. extra parameter is probably a display, but it could be the display
  303. colour or the background colour.  Probably the display colour is
  304. that given by the color statement.
  305.  
  306. * tran [on 0|off]
  307. No idea.  Was used around some cload and float statements.
  308.  
  309. * video mode
  310. Set the display mode to 'C' or 'L' (remember the image format types?).
  311. Usually the first statement in a command file.  C almost certainly
  312. refers to CGA which is 640 x 200 monochrome and L almost certainly
  313. to VGA which (in their case) is 320 x 200 x 256.
  314.  
  315. * waitkey [[delay[,label]]
  316. Wait up to delay units for the user to press a key (or forever if no
  317. delay time is given).  If the user presses a key and the label
  318. argument is present, transfer control to that label.
  319.  
  320. * window x1,y1,x2,y2,?
  321. Some kind of display control.  Probably a clipping window with appropriate
  322. coordinate translation (i.e., (0,0) becomes (x1,y1)).
  323.  
  324.  
  325.  
  326. This document was created by looking hard at a number of GL files,
  327. using cvt2gif to help decipher the image file format and looking
  328. at 1 or 2 animations on an RS-6000 running a PC emulator and using
  329. grasprt.  cvt2gif was very useful; grasprt under the PC emulator
  330. was painfully slow at times and didn't help my understanding
  331. much.  I've never even gotten close to a copy of the program for
  332. creating and editing GL files.
  333.  
  334. If you find out more about GL files, send me the changes so I can
  335. extend this document.  Feel free to include this as supplementary 
  336. documentation if you write a GL player.  Finally, here are some
  337. projects which could help find out more about GL files:
  338.  
  339. - Get cvt2gif and feed it small variations on .pic files to decipher
  340. the meaning of the missing header fields.  I may do this.
  341.  
  342. - Alter control files on some animations and see what effects they
  343. have.  Something easy would be to change the effect number on
  344. pfade statements (if that's what it is).  I don't have the hardware
  345. to do this.
  346.  
  347. - Look at the GRASP animation package and intuit what the commands
  348. mean by what control you have over generating animations.  This is
  349. probably the easiest way to get information.  I don't have GRASP,
  350. I don't know where to get it and I don't has a PC good enough to
  351. run it on.
  352.  
  353. ========================================================================
  354.  
  355. GRASP/Pictor Font format description                                  09/06/87
  356. ------------------------------------                                  --------
  357.  
  358. For convenience, we have chosen to adopt the IBM ROM font format for data, but
  359. to keep things manageable, we have added a 7 byte header which describes the
  360. font.
  361.  
  362. The seven byte header is defined as follows:
  363.  
  364. WORD    number of bytes in character data, plus this 7 byte header.
  365. BYTE    number of characters in set. 1-255 or 0 if 256.
  366. BYTE    ascii value of first character.
  367. BYTE    x size of character in pixels.
  368. BYTE    y size of character in pixels.
  369. BYTE    number of bytes in a single character.
  370.  
  371. As you can see from this header data, these limits apply:
  372.  
  373. 1) Maximum number of characters in set is 256.
  374. 2) Maximum character size is limited as: xsize/8 * ysize <256.
  375. 3) All character data plus 7 byte header must be <64K in size
  376.  
  377.  
  378. We use the following structure when writing programs that use fonts. Note the
  379. additional words at the end of the structure which allow you to keep the actual
  380. character data in a far segment.
  381.  
  382. struct chs {        /* character set structure */
  383.     unsigned int numchbyts;
  384.     unsigned char numchars;
  385.     unsigned char ascoff;
  386.     unsigned char chxsize;
  387.     unsigned char chysize;
  388.     unsigned char chbytes;
  389.     unsigned int chsseg;    /* segment of character data */
  390.     unsigned int chsofs;    /* offset in segment of character data */
  391. };
  392.  
  393.  
  394. So....A 256 character 8x16 font's header would look like:
  395.  
  396. numchbyts   = 4103         256 chars X 16 bytes/char + 7 bytes for header
  397. numchars    =    0         0 to represent 256
  398. ascoff      =    0         start with 0 character
  399. chxsize     =    8         8 dots wide
  400. chysize     =   16         16 dots high
  401. chbytes     =   16         1 byte wide x 16 dots high
  402.  
  403.  
  404. and a 96 character 11 X 18 font whose first character is SPACE's header would
  405. look like:
  406.  
  407. numchbyts   = 3456         96 chars X 36 bytes/char + 7 bytes for header
  408. numchars    =    0         0 to represent 256
  409. ascoff      =   32         start with 'SPACE' character
  410. chxsize     =   11         8 dots wide (this takes 2 bytes!)
  411. chysize     =   18         16 dots high
  412. chbytes     =   36         2 byte wide x 18 dots high
  413.  
  414. ========================================================================
  415.  
  416.  
  417.  
  418.                    PCPAINT/Pictor Page Format Description
  419.  
  420.                           Format by John Bridges.
  421.  
  422.                    Document by Microtex Industries, Inc.
  423.  
  424.  
  425.  
  426.  
  427.  
  428. Revision Date: 2/9/88
  429.  
  430.  
  431.  
  432. Global Notes:
  433. ------------
  434.  
  435. PCPAINT 1.0 - Revision 1.0 was developed for Mosue Systems in 1984 supported
  436. only BSAVE files in CGA 4 color mode. In the space between the scan buffers
  437. was a string that read PCPAINT 1.0 followed by 2 bytes which were the pallete
  438. and border information for that picture.
  439.  
  440. PCPAINT 1.5 - Revision 1.5 was the same as 1.0 except that it contained larger
  441. than screen images and also had a primative packing format. This was sold for
  442. so short a time that it won't be covered here.
  443.  
  444. PCPAINT 2.0 thru Pictor 3.1 - This document describes these formats. The file
  445. description is identical for all revisions in this range. However, in
  446. PCPAINT 2.0, the bit-planes were packed together so that the pictures
  447. resembled a PCjr picture, or 4 bits per pixel, 1 bit plane. Starting with
  448. Pictor 3.0, the files were saved with the bitplanes separated. This takes a
  449. little more memory in some cases, but the speed in loading and saving was a
  450. desireable consideration.
  451.  
  452. NOTE TO PROGRAMMERS: A good PCPAINT/Pictor file decoder will use the variables
  453.                      in the header to decode the image and thus be compatible
  454.                      with all formats since the October, 1985 release of
  455.                      PCPAINT 2.0.
  456.  
  457. Also please note that PCPAINT/Pictor are stored from the bottom up. This is
  458. opposite that of most of the screen adapters it supports. This really causes
  459. no problem, but be aware that you should use a Y table to look up scan lines.
  460. In all PCPAINT/Pictor pictures, the scan lines are continuous. If a picture 
  461. is to be displayed on a particular adapter, the programmer is responsible for
  462. using a y-table to properly interleave the lines if necessary.
  463.  
  464. Also note that Pictor was designed for speed, so no inter-mode loading is
  465. possible. If you are writing applications that create Pictor images that you
  466. want to load into Pictor, you must remain mode dependent. 
  467.  
  468. Header - A full description of the file header information.
  469.  
  470. offset    type    name    description
  471. -------    -------    -------    ----------------------------------------------------- 
  472.   0    word    marker    marker that is always 01234h
  473.  
  474.   2    word    xsize    x size of page in pixels 
  475.  
  476.   4    word    ysize    y size of page in pixels
  477.  
  478.   6    word    xoff    x offset into page where lower left hand corner of
  479.             viewport is located (default of 0 is ok)
  480.  
  481.   8    word    yoff    y offset into page where lower left hand corner of
  482.             viewport is located (default of 0 is ok)
  483.  
  484.  10    byte    bitsinf    bits 0-3 is the number of bits per pixel per bit
  485.             plane and bits 4-7 is the number of bit planes (so
  486.             4 color cga mode would be 02h and 16 color ega would
  487.             be 31h and plantronics 16 color would be 12h)
  488.  
  489.  11    byte    emark    marker that is always a 0ffh
  490.  
  491.  12    byte    evideo    single uppercase letter indicating which video mode
  492.             this picture was created in, can default to 0.
  493.  
  494.             0 - 40 col text
  495.             1 - 80 col text
  496.             2 - mono text
  497.             3 - 43 line text
  498.  
  499.             A=320x200x4 cga
  500.             B=320x200x16 pcjr, stbplus, tandy 1000
  501.             C=640x200x2 cga
  502.             D=640x200x16 ega
  503.             E=640x350x2 ega
  504.             F=640x350x4 ega
  505.             G=640x350x16 ega
  506.             H=720x348x2 hercules
  507.             I=320x200x16 plantronics
  508.             J=320x200x16 ega
  509.             K=640x400x2 AT&T or Toshiba 3100
  510.             L=320x200x256 vga
  511.             M=640x480x16 ega plus(video 7, tseng, paradise), vga
  512.             N=720x348x16 Hercules InColor
  513.             O=640x480x2 vga
  514.  
  515.  13    word    edesc    extra information descriptor defines what is in
  516.             the extra information that follows this header,
  517.             0=nothing
  518.             1=pallet (single byte) border (single byte)[CGA]
  519.             2=pcjr or non ECD 16 color registers (0-15), 1 byte each
  520.             3=EGA with ECD 16 color registers (0-63) 1 byte each
  521.             4=VGA 256 color info - 256 colors, 1 byte each rgb gun.  
  522.  
  523.  15    word    esize    size of extra information in bytes
  524.  
  525.  17    byte    edata[]    the actual extra data the size which is defined
  526.             by esize (at offset 15).
  527.  17+
  528.  esize    word    numblks    the number of packed blocks in this file. if this is
  529.             a zero, then data is unpacked. 
  530.  
  531.  
  532. Structures - These C structures describe the header information.
  533.  
  534. struct head {
  535.     unsigned int mark=0x1234;    /* marks begining of a page file */
  536.     unsigned int xsize;        /* x size of page */
  537.     unsigned int ysize;        /* y size of page */
  538.     unsigned int xoff;        /* current x offset into picture of viewport */
  539.     unsigned int yoff;        /* current y offset into picture of viewport */
  540.     unsigned char bitsinf;
  541. }
  542.  
  543. struct extra {
  544.     unsigned char emark=0xff;
  545.     unsigned char evideo;
  546.     unsigned int edesc;
  547.     unsigned int esize;
  548. }
  549.  
  550. int edata[esize];
  551. unsigned int numblks;
  552.  
  553. If the file is packed then what follows is a multi block packed file,
  554. otherwise (if the file is not packed, numblks=0) the actual data follows.
  555.  
  556. Bit planes follow each other in the file and when packed each bit plane
  557. must start in a new packed block.
  558.  
  559.  
  560. Packed Block Description
  561.  
  562.  
  563. Packed block header
  564.  
  565. PBSIZE    dw        ;Packed block size. The size of this block
  566. BSIZE    dw        ;Unpacked block size
  567. MBYTE    db        ;Unique marker byte. This is a byte that does not
  568.             ; exist in the current unpacked block. If no unique
  569.             ; byte exists, then pick one that is used rarely
  570.             ; to avoid too much redundancy.
  571.  
  572. Packed block data - variable size depending on whether 16 bit run is needed.
  573.  
  574. MARKER    db        ;mark a run (this is where MBYTE goes) 
  575. LENGTH    db        ;length of run. if 0, then look at BIGLEN
  576.  
  577. BIGLEN    dw        ;16 bit run count (only exists if LENGTH==0)
  578. DATA    db        ;byte to fill run with
  579.  
  580.  
  581. Example 1 - a 320x200, 4 color, packed page file, of a white screen. 
  582.  
  583.     dw    0x1234        ;marker
  584.     dw    320        ;x size
  585.     dw    200        ;y size
  586.     dw    0        ;x offset
  587.     dw    0        ;y offset
  588.     db    02h        ;2 bits per pixel and 1 bit plane
  589.  
  590.     db    0xff        ;extra info flag
  591.     db    'A'        ;vidmode
  592.     dw    1        ;extra area descriptor (pal and bord)
  593.     dw    2        ;bytes in extra area
  594.     db    2,0        ;pallet and border (extra information)
  595.  
  596.     dw    2        ;number of packed blocks
  597.  
  598. ;first block
  599.     dw    5+5        ;packed block size
  600.     dw    8192        ;unpacked block size
  601.     db    0        ;marker byte
  602.     db    0        ;mark a run
  603.     db    0        ;a 16 bit run count follows
  604.     dw    8192        ;16 bit run count
  605.     db    0xff        ;byte to fill run with
  606. ;second block
  607.     dw    5+5        ;packed block size
  608.     dw    7808        ;unpacked block size
  609.     db    0        ;marker byte
  610.     db    0        ;mark a run
  611.     db    0        ;a 16 bit run count follows
  612.     dw    7808        ;16 bit run count
  613.     db    0xff        ;byte to fill run with
  614.  
  615.  
  616.  
  617.  
  618. Example 2 - a 640x350, 16 color, packed page file, of a red screen (color 4).
  619.  
  620.     dw    0x1234        ;marker
  621.     dw    640        ;x size
  622.     dw    350        ;y size
  623.     dw    0        ;x offset
  624.     dw    0        ;y offset
  625.     db    31h        ;bits per pixel and 1 bit plane
  626.  
  627.     db    0xff        ;new extra info flag
  628.     db    'G'        ;vidmode
  629.     dw    3        ;extra area descriptor (pal and bord)
  630.     dw    16        ;bytes in extra area
  631.     db    0,1,2,3,4,5,14h,7
  632.     db    38h,39h,3ah,3bh,3ch,3dh,3eh,3fh
  633.  
  634.     dw    16        ;number of packed blocks
  635. ;block 1 of first bit plane
  636.     dw    5+5        ;packed block size
  637.     dw    8192        ;unpacked block size
  638.     db    0        ;marker byte
  639.     db    0        ;mark a run
  640.     db    0        ;a 16 bit run count follows
  641.     dw    8192        ;16 bit run count
  642.     db    0        ;byte to fill run with
  643. ;block 2 of first bit plane
  644.     dw    5+5        ;packed block size
  645.     dw    8192        ;unpacked block size
  646.     db    0        ;marker byte
  647.     db    0        ;mark a run
  648.     db    0        ;a 16 bit run count follows
  649.     dw    8192        ;16 bit run count
  650.     db    0        ;byte to fill run with
  651. ;block 3 of first bit plane
  652.     dw    5+5        ;packed block size
  653.     dw    8192        ;unpacked block size
  654.     db    0        ;marker byte
  655.     db    0        ;mark a run
  656.     db    0        ;a 16 bit run count follows
  657.     dw    8192        ;16 bit run count
  658.     db    0        ;byte to fill run with
  659. ;block 4 of first bit plane
  660.     dw    5+5        ;packed block size
  661.     dw    3424        ;unpacked block size
  662.     db    0        ;marker byte
  663.     db    0        ;mark a run
  664.     db    0        ;a 16 bit run count follows
  665.     dw    3424        ;16 bit run count
  666.     db    0        ;byte to fill run with
  667. ;block 1 of second bit plane
  668.     dw    5+5        ;packed block size
  669.     dw    8192        ;unpacked block size
  670.     db    0        ;marker byte
  671.     db    0        ;mark a run
  672.     db    0        ;a 16 bit run count follows
  673.     dw    8192        ;16 bit run count
  674.     db    0        ;byte to fill run with
  675. ;block 2 of second bit plane
  676.     dw    5+5        ;packed block size
  677.     dw    8192        ;unpacked block size
  678.     db    0        ;marker byte
  679.     db    0        ;mark a run
  680.     db    0        ;a 16 bit run count follows
  681.     dw    8192        ;16 bit run count
  682.     db    0        ;byte to fill run with
  683. ;block 3 of second bit plane
  684.     dw    5+5        ;packed block size
  685.     dw    8192        ;unpacked block size
  686.     db    0        ;marker byte
  687.     db    0        ;mark a run
  688.     db    0        ;a 16 bit run count follows
  689.     dw    8192        ;16 bit run count
  690.     db    0        ;byte to fill run with
  691. ;block 4 of second bit plane
  692.     dw    5+5        ;packed block size
  693.     dw    3424        ;unpacked block size
  694.     db    0        ;marker byte
  695.     db    0        ;mark a run
  696.     db    0        ;a 16 bit run count follows
  697.     dw    3424        ;16 bit run count
  698.     db    0        ;byte to fill run with
  699. ;block 1 of third bit plane
  700.     dw    5+5        ;packed block size
  701.     dw    8192        ;unpacked block size
  702.     db    0        ;marker byte
  703.     db    0        ;mark a run
  704.     db    0        ;a 16 bit run count follows
  705.     dw    8192        ;16 bit run count
  706.     db    0xff        ;byte to fill run with
  707. ;block 2 of third bit plane
  708.     dw    5+5        ;packed block size
  709.     dw    8192        ;unpacked block size
  710.     db    0        ;marker byte
  711.     db    0        ;mark a run
  712.     db    0        ;a 16 bit run count follows
  713.     dw    8192        ;16 bit run count
  714.     db    0xff        ;byte to fill run with
  715. ;block 3 of third bit plane
  716.     dw    5+5        ;packed block size
  717.     dw    8192        ;unpacked block size
  718.     db    0        ;marker byte
  719.     db    0        ;mark a run
  720.     db    0        ;a 16 bit run count follows
  721.     dw    8192        ;16 bit run count
  722.     db    0xff        ;byte to fill run with
  723. ;block 4 of third bit plane
  724.     dw    5+5        ;packed block size
  725.     dw    3424        ;unpacked block size
  726.     db    0        ;marker byte
  727.     db    0        ;mark a run
  728.     db    0        ;a 16 bit run count follows
  729.     dw    3424        ;16 bit run count
  730.     db    0xff        ;byte to fill run with
  731. ;block 1 of fourth bit plane
  732.     dw    5+5        ;packed block size
  733.     dw    8192        ;unpacked block size
  734.     db    0        ;marker byte
  735.     db    0        ;mark a run
  736.     db    0        ;a 16 bit run count follows
  737.     dw    8192        ;16 bit run count
  738.     db    0        ;byte to fill run with
  739. ;block 2 of fourth bit plane
  740.     dw    5+5        ;packed block size
  741.     dw    8192        ;unpacked block size
  742.     db    0        ;marker byte
  743.     db    0        ;mark a run
  744.     db    0        ;a 16 bit run count follows
  745.     dw    8192        ;16 bit run count
  746.     db    0        ;byte to fill run with
  747. ;block 3 of fourth bit plane
  748.     dw    5+5        ;packed block size
  749.     dw    8192        ;unpacked block size
  750.     db    0        ;marker byte
  751.     db    0        ;mark a run
  752.     db    0        ;a 16 bit run count follows
  753.     dw    8192        ;16 bit run count
  754.     db    0        ;byte to fill run with
  755. ;block 4 of fourth bit plane
  756.     dw    5+5        ;packed block size
  757.     dw    3424        ;unpacked block size
  758.     db    0        ;marker byte
  759.     db    0        ;mark a run
  760.     db    0        ;a 16 bit run count follows
  761.     dw    3424        ;16 bit run count
  762.     db    0        ;byte to fill run with
  763.  
  764.  
  765.  
  766. Example 3 - For more detail lets consider a block that isn't all the same.
  767. Say the data consists of 30 2's, and 8, a 4, and 300 1's.
  768.  
  769. ; the block would look like this 
  770.  
  771.     dw    5+10        ;packed block size
  772.     dw    332        ;30 + 1 + 1 + 300 bytes as above
  773.     db    ff        ;what to mark a run with,
  774.                                 ; because there are no ff's in our example.
  775.  
  776.     db    ff        ;mark a run 
  777.     db    30        ;8 bit run count
  778.     db    2        ;byte to fill run with - 2
  779.  
  780.     db    8        ;not a run marker, so must be data
  781.  
  782.     db    4        ;not a run marker, so must be data
  783.  
  784.     db    ff        ;mark a run
  785.     db    0        ;means 16 bit run count follows
  786.     dw    300        ;run count    
  787.     db    1        ;byte to fill run with - 1
  788.  
  789.  
  790. The actual unpacked data that resides in memory consists 2 seperate
  791. sections.
  792.  
  793. 1. The control structure: contains x size, y size, x offset, y offset,
  794.    segment of bit mapped data, number of bits per pixel and number of
  795.    additional bit planes. this information is kept in pcpaint's data segment.
  796.  
  797. 2. The actual bit mapped data: contains the actual page image, mapped from
  798.    bottom left (so bottom scan line is first). The data is contiguous within
  799.    each bit plane, so scan line 1 follows scan line 0 directly. the page
  800.    can and does cross segment boundires (a bit plane can be larger than
  801.    64k). each bit plane follows the previous but starts on a paragraph
  802.    boundary, the printer driver will be passed the offset in paragraphs
  803.    between bit planes and the number of additional planes.
  804.    The bit planes start with bit 0, each additional plane is the next bit.
  805.  
  806.  
  807.